home *** CD-ROM | disk | FTP | other *** search
/ Tech Arsenal 1 / Tech Arsenal (Arsenal Computer).ISO / tek-02 / makhelp.zip / MAKEHELP.DOC < prev    next >
Text File  |  1991-07-05  |  9KB  |  165 lines
  1.                                  MAKEHELP.DOC
  2.                         Documentation for MAKEHELP.EXE
  3.                 (C) Copyright 1991, Tansin A. Darcos & Company
  4.                           Commercial Rights Reserved
  5.                        "Above all else...We shall go on..."
  6.                               _"...And continue!"_
  7.                            Release 1.0, July 5, 1991
  8.  
  9.  
  10.  Document Overview
  11.  
  12.      This  document  is  used  to  describe  how to use the program MAKEHELP, a
  13.  program which generates the program code to create  an internal  help document
  14.  for use in a computer program.  This document is designed for the user of that
  15.  program who has some computer programming experience.
  16.  
  17.  
  18.  Introduction
  19.  
  20.      MAKEHELP was developed over 4 years ago to fill a need which I had  at the
  21.  time, to  create an on-line, pop-up help for use in a program.  The first time
  22.  I did this, I designed the help from scratch.  Then I had to change it  to add
  23.  new features,  which was  a pain in the, err, someplace.  So I sat down (after
  24.  making sure I was less sore) and wrote this program that takes a text file and
  25.  generates program  code to  use the text file in a program.  Note that you can
  26.  then take the generated program text file and adapt it as needed.  It has been
  27.  compiled using  Turbo Pascal  6.0, and  is being distributed to the public for
  28.  the first time.
  29.  
  30.  
  31.  How to use
  32.  
  33.      First, using any text editor, or word processor which creates non-document
  34.  text, including the editor supplied with Turbo Pascal or Turbo C, you will now
  35.  create the original text file which is the set of help messages which is to be
  36.  incorporated into  the program.   You  type in the sentences and examples that
  37.  are to show up on screen exactly as  you  want  them  to  appear.    Each help
  38.  message is  a paragraph of text and is separated from the next one by an empty
  39.  line.  Do not  confuse an  empty line  with a  blank line:  an empty  line has
  40.  nothing before  the RETURN  that you  type in;  a blank  line has  one or more
  41.  spaces.  If you want a blank line in the text of  a message,  be sure  you use
  42.  one space.   If  your editor  will not  save the one space lines, use a single
  43.  period, then edit the lines which only have a period as the  only character on
  44.  the  text,  to  change  them  to  a  single blank.  Save this text file to any
  45.  desired name.  For consistency, I suggest using  the extension  '.HLP' for the
  46.  text to be passed to MAKEHELP.
  47.  
  48.      Second, execute  MAKEHELP.  Press Return to skip the help screen.  Type in
  49.  the name of the text file  you  created  including  the  extension,  and press
  50.  RETURN.   MAKEHELP will then prompt you for the new name of the output file to
  51.  be included in your program.  It will suggest a file of  the same  name as the
  52.  one you  gave it, but with the extension .INC for the file it will create.  If
  53.  this is acceptable, press  RETURN, otherwise  type in  the name  of the output
  54.  file to  be created.   DO  NOT MAKE THIS THE SAME NAME AS THE ORIGINAL FILE OR
  55.  THE ORIGINAL FILE WILL BE DESTROYED.
  56.  
  57.      Third, in the constant definitions for your program, include a line of
  58.  
  59.                                {$I FILENAME.INC}
  60.  
  61.  where FILENAME.INC is the name of the output  file created  by MAKEHELP.   You
  62.  then create a help procedure to access this material, and where appropriate in
  63.  the program, you call the help procedure.   The sample  program CALC.PAS shows
  64.  how to  use the MAKEHELP facility in a program.  Another example occurs in the
  65.  MAKEHELP program itself; if you press the F1 key, a  help screen  pops up, and
  66.  you can select any number there for more information.  Generally,  you use the
  67.  generated indexes into the text that state starting  line number and number of
  68.  lines to display.  By copying  the help routine from CALC.PAS  you can display
  69.  help as appropriate.
  70.  
  71.  
  72.  Advantages
  73.  
  74.  One of  the competitive advantages in programming today is to make programs as
  75.  "easy to use" as possible; this means that things like context-sensitive help,
  76.  available at a touch of a key, become very important in the use of a program.
  77.  These features  could mean  the difference  between a program that is rejected
  78.  and one that can be sold.  In the case of shareware programs, this  could make
  79.  the difference  on whether someone pays for it or not.  This program isn't all
  80.  that important, but it is one of the things a computer can do well;  take over
  81.  some of the drudge work that a programmer otherwise has to accomplish.
  82.  
  83.  
  84.  About the generated code
  85.  
  86.  This program takes your input text document and changes it into code which may
  87.  then be  passed to  any version  of the  Turbo Pascal  Compiler.   I note this
  88.  because I  took the  same program which was written for Turbo Pascal version 3
  89.  and recompiled it using version 6.  The code it generates is  identical, and I
  90.  also note that the program generated its own on-line help.
  91.  
  92.  The generated code may be used with  Turbo Pascal version 3 or higher, or with
  93.  other compilers that support initialized constants.
  94.  
  95.  
  96.  Copying
  97.  
  98.  This document and the accompanying binary program are copyrighted.   The copy-
  99.  right holder hereby waives  his exclusive  right to  reproduce copies to allow
  100.  the reproduction of this instruction  guide and the binary program, as well as
  101.  the enclosed sample program 'CALC.PAS', the help file 'CALC.HLP' and the  help
  102.  code file 'CALC.INC' which is generated by MAKEHELP.EXE.  All other rights are
  103.  reserved.  Any entity providing a copy of this set of files  may charge  a fee
  104.  for  reproduction  of this  set of  files.  The  copyrights on  the additional
  105.  sources provided because of registration are not waived.
  106.  
  107.  
  108.  Registration
  109.  
  110.  This program  is not  in the public domain.  If you use it on programs you are
  111.  distributing, you should send me  some money for it.  This could  encourage me
  112.  to develop other programs.   You have  three options.  Send  a little money to
  113.  ask questions.   Send a little more money and I will thank you, and  I'll send
  114.  you something back  in return.  Send  even  more money  and I'll  send you the
  115.  source to this program.
  116.  
  117.  If you  have any  questions about  the program, send a self-addressed, stamped
  118.  envelope and $1.25 per question and I'll  answer  them.    Or  send  $1.50 per
  119.  question and  your return address and I'll respond.  If you want a copy of the
  120.  latest version of this program, send $1.50.  (Indicate if  you want  5 1/4" or
  121.  3.5" disk; for 3 1/2", say if you want 360K or 720K.)  If you  send an  E-Mail
  122.  code for Internet, Relaynet, Fidonet or WWIVNET I may respond electronically.
  123.  
  124.  If you  want to  register this program, send $9.95.  This gets you a thank you
  125.  and the next version if one comes out.  I  will also  send you  the additional
  126.  code I use to  generate pop-up windows and  fast screen updates.  You may also
  127.  obtain up to 3 questions by mail  at no charge;  I send you the prepaid  post-
  128.  cards and I will respond in the same manner.   You  can also get more than the
  129.  first 3 questions answered by sending an envelope,  your question  and 20c for
  130.  return postage.  You may  send up to five questions by electronic mail. Please
  131.  note if you  got this program from a shareware disk  distributor that  I don't
  132.  get any money out of their diskette charge.
  133.  
  134.  If you send $15.00 or more, you get the $9.95 prize, plus unlimited electronic
  135.  mail support, plus the  source code to  MAKEHELP, plus the special  source for
  136.  the hypertext help package, allowing the use of HUGE help files which  are too
  137.  big to keep in memory.
  138.  
  139.  Payment of  a registration includes the right  to unlimited use of the program
  140.  but does not include the right to make  copies of the source to it for others.
  141.  If you wish to include the source to MAKEHELP in an  application  or compiler,
  142.  write or send an electronic mail message for details, or if you want a special
  143.  version for a different language.  ALL PRICES ARE SUBJECT  TO CHANGE  IF THERE
  144.  ARE CHANGES IN THE  CONDITIONS UNDER WHICH IT IS  POSSIBLE FOR  THE PRODUCT OR
  145.  SUPPORT FOR THE PRODUCT CAN BE PROVIDED.
  146.  
  147.  Persons who register this program who  are eligible  to use  telephone support
  148.  may  do  so  in  lieu  of  mail  support.  Return responses will be by mail or
  149.  electronic mail, fax or telephone depending on the size of the response.
  150.  
  151.  In place of receiving a response  by  mail,  you  may  receive  a  response by
  152.  facsimile if you supply your fax number.
  153.  
  154.  
  155.  Send payments to
  156.  
  157.  Paul Robinson
  158.  C/O Tansin A. Darcos & Company
  159.  P O Box 70970
  160.  Washington, DC 20024
  161.  
  162.  My electronic  mail addresses  will be given out with the receipt for payment.
  163.  I am on the FIDONET, RELAYNET, INTERNET, WWIVNET networks and several national
  164.  and local BBSs.
  165.